# Other issue

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# What should I do if the device becomes excessively hot?

## Confirm whether the temperature is actually too high

Run the following command to obtain the current device temperature:

```bash
qpi-config dump temperature
```

If the temperature exceeds 80 °C, take cooling measures immediately.

## Identify the heat source

Check CPU utilization and frequency:

```bash
# Check CPU utilization.
top -b -n 1 | head -20

# Check the operating frequency of each CPU core to determine whether it remains at the maximum frequency.
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq

# Check whether the performance governor is enabled.
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
```

Check GPU utilization:

```bash
cat /sys/class/kgsl/kgsl-3d0/gpu_busy_percentage 2>/dev/null
cat /sys/class/kgsl/kgsl-3d0/max_gpuclk 2>/dev/null
```

Check storage utilization:

```bash
iostat -x 1 3   # Check %util.
```

## Software cooling measures

Lower the CPU frequency:

```bash
# Check available frequencies.
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies

# Set the maximum frequency, for example, to 1.6 GHz.
echo 1651200 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq
```

Switch the CPU governor to schedutil:

```bash
echo schedutil > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
```

Lower the maximum GPU operating frequency:

```bash
# Check available frequencies.
cat /sys/class/kgsl/kgsl-3d0/devfreq/available_frequencies

# Set the maximum frequency, for example, to 550 MHz.
echo 550000000 > /sys/class/kgsl/kgsl-3d0/devfreq/max_freq
```

Check for processes with abnormal CPU usage:

```bash
ps aux --sort=-%cpu | head -10
```

## Physical cooling measures

- Place the Quectel Pi H1 in a well-ventilated environment.

- Install an active cooling module. The fan should increase its speed automatically when the device temperature exceeds the configured threshold.

# What should I do if a library does not work correctly?

## Identify and classify the issue

- Link error: The compiler reports *cannot find -lxxx*, or the error *cannot open shared object file* occurs at runtime.

- Runtime crash: The application reports *undefined symbol: xxx* or triggers a *Segmentation fault*.

- Functional error: The library loads successfully, but a specific API does not respond or returns an unexpected error code.

## Check whether the library file exists and verify the library search path

```bash
# 1. Locate the library.
find /usr/lib /usr/local/lib /lib -name "libxxx.so*"

# 2. Check whether the dynamic linker can locate the library.
ldconfig -p | grep libxxx

# 3. Check whether LD_LIBRARY_PATH contains the directory.
echo $LD_LIBRARY_PATH
```

If the library is in a nonstandard directory, set *LD_LIBRARY_PATH*, or add the directory to a configuration file under */etc/ld.so.conf.d/* and run **ldconfig** to update the cache.

## Check dependencies to resolve undefined symbols

```bash
# Check the library dependencies (safer than ldd because it does not execute code).
readelf -d /path/to/libxxx.so | grep NEEDED

# Check whether a symbol is defined in the library.
nm -D /path/to/libxxx.so | grep "  T " | grep symbol_name

# Alternatively:
readelf -s /path/to/libxxx.so | grep symbol_name
```

An undefined symbol usually indicates a library version mismatch or a missing dependency. If the symbol exists but the application still reports an error, the cause may be link order or ABI incompatibility.

## Check library version and ABI compatibility

```bash
# Check the embedded library version string.
strings /path/to/libxxx.so | grep -i version

# Check the library's SONAME (the name used by the dynamic linker).
readelf -d /path/to/libxxx.so | grep SONAME
```

If the application was linked against *libxxx.so.1* at build time but the system provides only *libxxx.so.2*, ABI incompatibility may still cause the application to crash at runtime even if the newer library exports the required symbols. After confirming that the two library versions are ABI-compatible, you can create a symbolic link (**ln -s libxxx.so.2 libxxx.so.1**) as a temporary workaround. For a long-term solution, install a library version compatible with the application or rebuild the application against the library available on the system.

## Trace dynamic library loading at runtime (to diagnose loading failures)

```bash
# 1. Check which libraries the dynamic linker loads and whether it loads an incorrect version.
LD_DEBUG=libs ./your_app 2>&1 | grep libxxx

# 2. Use strace to trace attempts to open library files.
strace -e openat,open ./your_app 2>&1 | grep libxxx

# 3. If the application crashes immediately after startup, use gdb to locate the crash.
gdb ./your_app
(gdb) run
(gdb) bt   # Check the call stack after the crash.
```

# How can I update a third-party driver?

1. Obtain the official SDK. See [Image build](<../../Operating system/Yocto Linux/Image build/Image build.md>) for download instructions.

2. Add the third-party driver source code under *sources/quectel-src/kernel*.

3. Add the device tree node for the peripheral to *sources/quectel-src/kernel/qcom-6.6/arch/arm64/boot/dts/qcom/qcs6490-idp-pi.dts*.

4. Build the system image, flash it to the Quectel Pi H1, and then test the driver functionality.

# What should I do if system performance is poor?

Poor performance is usually caused by a combination of CPU scheduling, memory pressure, storage I/O, thermal throttling, and software configuration.

## Identify the bottleneck

```bash
# 1. Check the overall system load (1/5/15 minute).
uptime
# A sustained load average above the number of CPU cores (for example, above 8.0 on an 8-core system) indicates insufficient CPU capacity.

# 2. Check CPU utilization by state (user, system, soft interrupt, and idle).
mpstat -P ALL 1 3

# 3. Check memory and swap usage (whether swap is in use).
free -h
# Less than 10% available memory with nonzero swap usage indicates memory pressure.

# 4. Check for a storage I/O bottleneck (a %util value close to 100% indicates that the disk is a bottleneck).
iostat -x 1 3

# 5. Check the temperature and CPU frequency (determine whether thermal throttling has occurred).
qpi-config dump temperature
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq
```

Interpret the key metrics as follows:

- High %us: CPU-intensive tasks.

- High %sy: Excessive system call or driver overhead (such as software interrupt).

- High %wa: Storage I/O bottleneck.

- High %si: Excessive software interrupts (such as BLOCK softirq).

- Temperature above 80 °C: Potential thermal throttling.

- Very little available memory in **free -h**: Memory pressure.

## Apply targeted optimization

### CPU bottleneck (%us or %sy consistently above 60%)

- Identify the processes with the highest CPU utilization.

- Reduce the load generated by cameras and other peripherals.

- Increase the real-time priority of critical threads, for example, by adjusting the scheduling policy.

### Memory bottleneck ( low available memory and nonzero swap usage)

- Identify the Top 10 processes with the highest memory usage.

- Remove unnecessary log files.

- Check for DMA-BUF or ION memory leaks.

### Storage I/O bottleneck (%util in iostat close to 100%)

- Identify the process with the highest write I/O activity.

- Reduce unnecessary log writes.

- Check for processes that write files too frequently.

### Thermal throttling (frequency reduction caused by high temperature)

- Confirm whether the system has triggered frequency throttling.

- Apply active physical or software cooling measures.

# How can I configure a service to start at boot?

*systemd* is the standard init system used by most mainstream Linux distributions, including Yocto-based systems. It provides dependency management, automatic restart, and environment variable configuration.

## Create a service unit file

Create a .service file under */etc/systemd/system/* such as *my-camera.service*:

```
[Unit]
Description=My Camera Service
After=network.target   # Start after the network is available (adjust as needed).

[Service]
Type=simple            # Other types include forking and oneshot.
ExecStart=/usr/bin/my_script.sh
Restart=on-failure     # Restart automatically after a failure.
User=root              # Specify the user that runs the service (typically root).
WorkingDirectory=/opt/my_app

[Install]
WantedBy=multi-user.target   # Start the service when the system enters multi-user mode.
```

## Enable and start the service

```bash
# Reload the systemd configuration.
sudo systemctl daemon-reload

# Enable the service to start at boot (creates a symbolic link).
sudo systemctl enable my-camera.service

# Start the service immediately (optional).
sudo systemctl start my-camera.service

# Check the service status.
sudo systemctl status my-camera.service
```

# How can I install a third-party driver?

1. Obtain the driver module file: Obtain the third-party driver source code and cross-compile it in an environment that matches the Quectel Pi H1's kernel version to generate a .ko module file.

2. Transfer the driver module file: Transfer the compiled .ko file to the Quectel Pi H1 through scp, adb, or a USB flash drive.

3. Load and unload the driver:  
  Run **insmod** to load the driver:  
  ```bash
  insmod your_driver.ko
  ```  
  Run **rmmod** to unload the driver:  
  ```bash
  rmmod your_driver
  ```  
  Run **lsmod** to list all loaded modules:  
  ```
  lsmod
  ```

# What should I do if no solution is available?

1. Visit [Technical FAQs](<https://www.quectel.com/faqs-technical/>).

2. Post a question on the [Quectel Forums](<https://forums.quectel.com/>).